---
title: Guide Documents > Swagger Document > TypeScript Swagger Editor
---
import { EDITOR_EXAMPLES } from "../../../src/constants/EDITOR_EXAMPLES";
import EditorMovie from "../../../src/movies/editor/EditorMovie";
import { HyperLink } from "../../../src/components/basic/HyperLink";
import { List } from "../../../src/components/basic/List";
import { ListItem } from "../../../src/components/basic/ListItem";

## Outline
![Example Case](/images/editor/stackblitz.png)

Swagger-UI with Cloud TypeScript Editor with embedded SDK.

`@nestia/editor` is a combination of Swagger-UI and web-based TypeScript editor (of [StackBlitz](https://stackblitz.com/)) embedding [SDK (Software Development Kit) library](./sdk/sdk) generated by [`@nestia/migrate`](./migrate) from an OpenAPI document. With the `@nestia/editor`, you can easily test the backend API with TypeScript code, and it is much convenient than the traditional way of using Swagger UI, due to type checking and auto-completion of the TypeScript.

Also, `@nestia/editor` provides [Mockup Simulator](./sdk/simulator) of the backend API functions. With the mockup simulator, you can start the frontend (or client) development even when the backend API functions have not been implemented yet. Furthermore, `@nestia/editor` supports automatic [e2e (end-to-end) test functions' generation](./sdk/e2e), so that you can easily validate the backend API functions with the automatically generated test codes.

Here are the some example projects generated by `@nestia/editor`. Traveling those example projects, you may understand how to utilize the `@nestia/editor`. Let's start the type safe API interaction development with `@nestia/editor`!

{<List>
  <ListItem> Concepts
    <List>
      <ListItem> SDK: collection of typed <code>fetch</code> functions with DTO structures </ListItem>
      <ListItem> Mockup Simulator: embedded backend simulator in the SDK </ListItem>
    </List>
  </ListItem>
  <ListItem> Demo Editors
    <List>
      {EDITOR_EXAMPLES.map((example) => (
        <ListItem>
          <HyperLink 
            href={`/editor/?url=${encodeURIComponent(example.swagger)}&package=${encodeURIComponent(example.package)}&simulate=true&e2e=true`} 
            target="_blank">
            {example.title}
          </HyperLink>
        </ListItem>
      ))}
    </List>
  </ListItem>
</List>}

<EditorMovie />

> Put your `swagger.json` file, then `@nestia/editor` be opened.




## Frontend Setup
### React Library
```typescript
import { NestiaEditorIframe } from "@nestia/editor";
import { SwaggerV2, OpenApiV3, OpenApiV3_1 } from "@samchon/openapi";

const document: SwaggerV2 | OpenApiV3 | OpenApiV3_1;

<NestiaEditorIframe swagger={document} 
                    package="your-package-name"
                    e2e={true} 
                    simulate={true} />
<NestiaEditorUploader />
```

Install `@nestia/editor` and import one of below components.

If you've prepared the Swagger Document to serve, you can directly launch the cloud editor by using the `NestiaEditorIframe` component. Otherwise you want to provide a "Swagger File Uploader" for dynamic purpose, utilize the `NestiaEditorUploader` component instead.

  - `NestiaEditorIframe`: directly launch the cloud editor by given document
  - `NestiaEditorUploader`: upload the `swagger.json` file and launch the cloud editor




### Static Hosting
![Unzipped](/images/editor/unzipped.png)

> [💾 https://nestia.io/downloads/editor.zip](/downloads/editor.zip)

Unzip and place your `swagger.json` file into the extracted directory.

Just download unzip the above [`editor.zip`](/downloads/editor.zip) file, and place your `swagger.json` (or `swagger.yaml`) file into the extracted directory. When you open the unzipped `index.html` in your browser, you can see the `@nestia/editor` is serving the "TypeScript Swagger Editor" application with your `swagger.json` (or `swagger.yaml`) file.

Also, if you want to specify the package name, or activate the Mockup Simulator, open the `index.html` file of unzipped and edit some variables like below. Guiding the users th fill these `package`, `simulate` and `e2e` query parameters like `http://localhost/?simulate=true&e2e=true` can be an alternative way. 

By the way, if you do not place the `swagger.json` (or `swagger.yaml`) file into the directory, the `@nestia/editor` will just show you the "Swagger File Uploader" (`NestiaEditorUploader`) instead.

```html filename="editor/index.html" showLineNumbers {14-16}
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, height=device-height, initial-scale=1, minimum-scale=1.0, maximum-scale=3.0s"
    />
    <title>Nestia Editor</title>
    <script type="module"  src="./assets/index-DwHERS4Q.js"></script>
  </head>
  <body style="width: 100%; height: 100%; margin: 0px; overflow: hidden;">
    <div id="root" style="width: 100%; height: 100%"></div>
    <script>
      window.package = "@ORGANIZATION/PROJECT";
      window.simulate = false; 
      window.e2e = false;
    </script>
  </body>
</html>
```




### `<iframe>` Embedding
```html
<iframe url="https://nestia.io/editor/?url={URL_ADDRESS}&package={NAME}&simulate=true&e2e=true"></iframe>
```

You also can embed the `@nestia/editor` with static URL address.

When embedding the `@nestia/editor` application through the `<iframe>` tag, fill the `url` query parameter with the URL address of your `swagger.json` (or `swagger.yaml`) file. Also, the `simulate` and `e2e` query parameters are optional, but recommended to be filled with `true` for the best experience. As you know, they activate the Mockup Simulator and automatic e2e test functions' generation.

By the way, if you do not fill the `url` query parameter, the `@nestia/editor` will just show you the "Swagger File Uploader" (`NestiaEditorUploader`) instead.

If you wanna see the example cases of the `<iframe>` embedding, let's see the below list again.

{<List>
  {EDITOR_EXAMPLES.map((example) => (
    <ListItem>
      {example.title}{": "}
      <HyperLink 
        href={`/editor/?url=${encodeURIComponent(example.swagger)}&package=${encodeURIComponent(example.package)}&simulate=true&e2e=true`} 
        target="_blank">
        https://nestia.io/editor/?url={example.swagger.split("/").at(-1)}
      </HyperLink>
    </ListItem>
  ))}
</List>}




## Backend Setup
### Editor Module
```typescript filename="src/main.ts" showLineNumbers {1, 18-25}
import { NestiaEditorModule } from "@nestia/editor/lib/NestiaEditorModule";
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

import { AppModule } from './app.module';

const bootstrap = async (): Promise<void> => {
  const app = await NestFactory.create(AppModule);
  const config = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const documentFactory = () => SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, documentFactory)

  await NestiaEditorModule.setup({
    path: "editor",
    application: app,
    swagger: "/api-json",
    package: "your-package-name",
    simulate: true,
    e2e: true,
  });
  await app.listen(3000);
};
bootstrap().catch(console.error);
```

In the NestJS, you can serve the Nestia Editor by `NestiaEditorModule.setup()` function.

Note that, if you've configured the path parameter of the `SwaggerModule.setup()` function (of `@nestjs/swagger`) as `api`, its URL path of the composed Swagger Document is `/api-json`. Fill the `/api-json` URL path into the `swagger` parameter of the `NestiaEditorModule.setup()` function.

Also, don't forget to configure the additional properties like `package`, `simulate` and `e2e` for the best experience. Even though these properties are optional, but recommended to be fully filled with the proper values.

  - `package`: Name of the SDK package generated in the editor
  - `simulate`: Whether to compose mockup simulator or not
  - `e2e`: Whether to compose e2e automated test functions or not